Inside Macintosh: OpenDoc Cookbook /

Chapter 2 - SamplePart Tutorial

Defining Resources

SamplePart uses Mac OS resources to define and store various types of structured data, as described in this section. Most of SamplePart's resources are defined in the file SamplePart.r. Other resource data used in SamplePart, such as 'PICT' data, is contained in the file SamplePartOtherResources.rsrc. SamplePart.r and SamplePartOtherResources.rsrc are compiled to produce the resource objects files SamplePart.PPC.rsrc (for the PowerPC version) and SamplePart.68k.rsrc (for the 68K version).

OpenDoc-OLE Interoperability

OpenDoc provides interoperability with OLE (Object Linking and Embedding) technology, enabling OLE servers to be embedded in OpenDoc container parts and OpenDoc parts to be embedded in OLE applications. For your part to be embedded directly in an OLE application, it must have its own OLE class identifier (CLSID), an alphanumeric string that uniquely identifies your part to the OLE runtime system. On the Mac OS platform, parts maintain their CLSID in a resource of type 'olcr'.

To obtain an OLE class identifier, you must contact Microsoft Corporation. To do so, log on to CompuServe, enter GO "WINOBJ" and post a public or private message requesting the number of class identifiers you need. Include your company's name, address, and telephone number. If you don't specify a number, Microsoft allocates a block of 250 OLE class identifiers for each request.

In your 'olcr' resource, you must represent your CLSID as a string delimited by braces and double quotation marks. Listing 2-55 shows SamplePart's OLE interoperability resource definition.

Listing 2-55 SamplePart OLE interoperability resource

resource 'olcr' (0, "OLE Class ID")
{
"{80C11F40-7503-8576-00D01113F11}";
};

Menu IDs

Menu IDs on the Mac OS are positive short integers, and hierarchical menu IDs must be in the 1-byte range. (Negative values are reserved.) Menu IDs must be the same as the menu resource ID if the menu is resource based.

Because all menus installed in the Mac OS menu bar must have unique IDs, there is potential conflict among the OpenDoc document shell and container applications, shell plug-ins and services, and the currently active part. Therefore, you should use the following ranges for regular menus:

Document shell and container applications	255-16383
Plug-ins and services	16384-20000
Part editors	20001-32767

You should use the following ranges for hierarchical menus:

Document shell and container applications	0-127
Plug-ins and services	128-193
Part editors	194-254

Since there may be multiple plug-ins or services, they must assign their IDs dynamically. That is, a plug-in should choose an ID within the specified range and look for a menu with that ID. If one is found, the plug-in should add 1 to the ID and try again.

Bundle Resources

SamplePart includes certain resource definitions for its own purposes, such as icons for its icon views. The Finder uses bundle resources (type 'BNDL') to associate conventional applications and documents with each other and with the icons it displays to the user for them. The bundle resource contains the application's four-letter signature and the resource ID numbers of its signature, icon list, and file reference resources. Refer to Inside Macintosh: Macintosh Toolbox Essentials for more information about bundle resources and the Finder interface.

In OpenDoc, a part editor has two or more bundle resources; SamplePart has three: editor, viewer, and document. Bundle resources associate part editor and viewer icon families (specified according to type) with the shared library file containing their executable code (specified according to signature). Whereas conventional Mac OS applications have a type of 'APPL', part editors and viewers have the type 'shlb'. SamplePart's editor signature is 'SPED' and its viewer signature is 'SPVW'.

OpenDoc parts are not owned by their part editors in the way conventional Mac OS documents are owned by their creator applications. Rather, all OpenDoc documents have a creator type of 'odtm'. They are associated with their Finder icons by means of their type, which can be unique because it does not need to indicate the type of data contained by the document. You could use the same four-letter code to represent your part editor and documents. SamplePart documents, however, use the type 'SPDC'.

Stationery documents are very important in OpenDoc because users typically see and manipulate stationery--double-clicking or dragging a stationery icon in the Finder--to create an instance of a part. Stationery documents differ from regular documents only in the Finder Info bit that is set for stationery; they share the same file type and creator. You must include a stationery icon family in your document bundle resource with a file type identical to your document file type except that its first letter is a lowercase s (regardless of the first letter of the document file type). The Finder then makes the proper association between the stationery icons and documents with their stationery bit set. So, SamplePart's stationery icons are associated with a type of 'sPDC'.

Editor, viewer, and document signatures should be registered with Apple Developer Technical Support. SamplePart maintains these definitions in the file SamplePartOtherResources.rsrc. You can view the resources themselves using a resource editor such as ResEdit.

Version Numbers

Parts need to maintain three separate sets of version numbers that are necessary to the part's correct operation: CFM (Code Fragment Manager) version numbers, Finder file version numbers, and SOM class version numbers. These version numbers should be synchronized.

All of these types of version numbers include one major and one minor number, separated by a decimal point. In addition, CFM and Finder version numbers include a second minor version number called the fix version. For example, in the version number 2.3.1, the major portion is 2, and the minor portion is 3.1. Major version numbers have a range of 0-99; both minor version numbers have a range of 0-9. (The Code Fragment Manager and the Finder also provide for development stage designations. You can ignore these designations, but be aware that the Code Fragment Manager uses them if provided.)

Version numbers are maintained in binary-coded-decimal format. For example, using hexadecimal notation to represent the binary, the version number 2.3.1 is represented as 0x0231. Note that the 3 and the 1 are both in the same byte.

CFM version numbers enable the Code Fragment Manager of the Mac OS to find and load the correct version of the part editor's shared library. CFM version numbers are defined in the part's 'cfrg' resource, shown in Listing 2-58. The Finder version numbers are displayed by the Finder in response to the Get Info menu command. SOM version numbers are used in the SOM Interface Definition Language (.idl) file; they ensure compatibility between the definition and implementation of SOM classes.

SamplePart includes a file, SamplePartVers.h, that contains a set of compiler definitions to generate all three version numbers correctly. This file is included in SamplePart.r and som_SamplePart.idl. In addition, you must specify the correct version numbers to the linker in your makefile (for MPW) or project preferences (for integrated environments).

CFM version numbers are explained in Inside Macintosh: PowerPC System Software. Finder version numbers are explained in Inside Macintosh: Macintosh Toolbox Essentials. SOM version numbers are discussed in the SOMobjects Developer Toolkit Users Guide from IBM.

Listing 2-56 shows SamplePart's version number constant definitions. These constants are used in the file SamplePart.r, as shown in Listing 2-57, which shows SamplePart's Finder version resource definitions, and Listing 2-58, which shows SamplePart's code fragment resource definition. The version number constants are used again in the file som_SamplePart.idl, which is described in Appendix B, "System Object Model."

Listing 2-56 SamplePart version number definitions

// Development stages
#define dsUndefined         0x00
#define dsPreAlpha          0x20
#define dsAlpha             0x40
#define dsBeta              0x60
#define dsFinal             0x80
#define dsReleased          dsFinal
#define dsGoldenMaster      dsFinal


//  Change often 

// Current major version (version = major.minor.fix)
#define currentMajorVersion  1

// Current minor version (version = major.minor.fix)
#define currentMinorVersion  0

// Current fix version (version = major.minor.fix)
#define currentFixVersion    0

// Development stage
#define developmentStagedsFinal

// Prerelease number
#define preReleaseNumber     0

// Short version string
#define shortVersionStr      "1.0"


//  Change seldom 

// Old compatibility definition major version (for CFM only)
#define oldCompDefnMajorVersion  0

// Old compatibility definition minor version (for CFM only)
#define oldCompDefnMinorVersion  0

// Old compatibility definition fix version (for CFM only)
#define oldCompDefnFixVersion    0

// Prerelease number
#define oldCompDefnPreRelNumber  0

// Development stage
#define oldCompDefnDevStage      dsUndefined


//  Generated version numbers 
//       (Don't change!!)

#define currentVersion (currentMajorVersion<<24)+(currentMinorVersion<<20) \
                  +(currentFixVersion<<16)+(developmentStage<<8)+preReleaseNumber
#define compatibleVersion (oldCompDefnMajorVersion<<24)+(oldCompDefnMinorVersion<<20) \
                     +(oldCompDefnFixVersion<<16)+(oldCompDefnDevStage<<8) \
                     +oldCompDefnPreRelNumber
#define finderMinorVersion (currentMinorVersion<<4)+(currentFixVersion<<0)

Listing 2-57 SamplePart Finder version resources

resource 'vers' (1) {
   currentMajorVersion,
   finderMinorVersion,
   developmentStage,
   preReleaseNumber,
   verUS,
   shortVersionStr,
   shortVersionStr", © Apple Computer, Inc. 1994-1995"};

resource 'vers' (2) {
   currentMajorVersion,
   finderMinorVersion,
   developmentStage,
   preReleaseNumber,
   verUS,
   shortVersionStr,
   "OpenDoc(TM) Sample Code"
};

Code Fragment Resources

Because SOM on the Mac OS depends on the Code Fragment Manager, your part editor's shared library needs to include a code fragment ('cfrg') resource. It is important that the name for the fragment description be the editor ID; if your development environment automatically assigns the name of the library file to the fragment description, you need to change it.

Listing 2-58 shows SamplePart's code fragment resource definition from the file SamplePart.r.

Listing 2-58 SamplePart code fragment resource

resource 'cfrg' (0) {
   {  /* [1] */
#ifdef _68KBUILD_
      kMotorola,
#else
      kPowerPC,
#endif
      kFullLib,
      currentVersion,
      compatibleVersion,
      kDefaultStackSize,
      kNoAppSubFolder,
      kIsLib,
      kOnDiskFlat,
      kZeroOffset,
      kWholeFork,
      kSamplePartID,/* This must be the class ID */
      /* [2] */
#ifdef _68KBUILD_
      kMotorola,
#else
      kPowerPC,
#endif
      kFullLib,
      currentVersion,
      compatibleVersion,
      kDefaultStackSize,
      kNoAppSubFolder,
      kIsLib,
      kOnDiskFlat,
      kZeroOffset,
      kWholeFork,
      kPartClassName /* This must be the SOM class name */
                     /* for this part */
   }
};

Name-Mapping Resources

Dynamic binding is the process by which OpenDoc matches a part editor at runtime to a part appearing in a document. On the Mac OS, dynamic binding is implemented through a set of six name-mapping resources (of type 'nmap') in the shared library files of part editors. These resources describe various aspects of the relationships between content and part editors. OpenDoc uses these resources to construct name spaces in the name-space object, maintained by the session object, when the user opens a document.

The name mappings that SamplePart defines are described in the following sections. SamplePart's 'nmap' resources are defined in the file SamplePart.r. The constant definitions strings on which they depend are defined in the file SamplePartDef.h. The listings in the following sections combine fragments of these files to illustrate the name mappings.

Mapping Kind to Category

A part stores its content in its contents property as one or more part kinds, and part kinds belong to one or more part categories. OpenDoc requires part editors to map their part kinds to their part categories.

A part kind identifies its data format uniquely. A kind designation is an ISO string (7-bit ASCII) identifying the part kind, usually in a company-specific way, for proprietary and standard data types. For example, the following could be kind designations: SurfCorp:SurfText, SurfCorp:Picture:BlackAndWhite, and SurfCorp:Picture:Color.

The part category of a part's content defines a generic classification of its data format. For example, OpenDoc recognizes part categories of plain text, styled text, object-based graphics, 3D object-based graphics, and many others. For a list of OpenDoc's standard part categories with explanations, see the OpenDoc Programmer's Guide for the Mac OS.

A part's kind-to-category mapping must specify the category (or categories) for each kind the editor supports. A kind can belong to more than one category, in which case the categories are unordered. OpenDoc uses the information from this mapping to help the user define a default editor for each category.

Listing 2-59 shows SamplePart's very simple kind-to-category mapping.

Listing 2-59 Kind-to-category mapping

#define kSamplePartKind        kODISOPrefix "Apple:Kind:SamplePart"

#define kSamplePartCategory    kODISOPrefix "Apple:Category:Sample Code"

#define kBaseResourceID        20001
#define kKindCategoryMapId     kBaseResourceID+1

resource kODNameMappings (kKindCategoryMapId) {
   kODKind,
   {  /* array Types: 1 elements */
      /* [1] */
      kSamplePartKind,
      kODIsAnISOStringList
      {
         {  /* array ClassIDs: 1 elements */
            /* [1] */
            kSamplePartCategory
         }
      }
   }
};

Mapping Editor to Kind

OpenDoc requires each part editor to map its editor identifier to its part kinds. An editor identifier represents a part editor. It comprises the editor's SOM module name and ODPart subclass name, separated by a double colon. A part kind designation represents the unique data format of a part editor, as described in the previous section.

A class identifier is associated with one or more part kinds. The part kinds must be listed in decreasing order of fidelity.

Listing 2-60 shows SamplePart's editor-to-kind mapping.

Listing 2-60 Editor-to-kind mapping

#define kPartClassName"som_SamplePart"#define kSamplePartID"SampleCode::"kPartClassName
#define kSamplePartKindkODISOPrefix "Apple:Kind:SamplePart"#define kEditorKindMapIdkBaseResourceID+2
resource kODNameMappings (kEditorKindMapId) {
   kODEditorKinds,
   {  /* array Types: 1 elements */
      /* [1] */
      kSamplePartID,
      kODIsAnISOStringList
      {
         {  /* array ClassIDs: 1 elements */
            /* [1] */
            kSamplePartKind
         }
      }
   }
};

Mapping ISO Strings to User-Readable Names

OpenDoc requires each part editor to map its editor identifier, part kind, and part category to user-readable strings. OpenDoc manipulates editor identifiers, part kinds, and part categories as ISO strings, which are not appropriate for display to the user. OpenDoc requires that user-readable text be in the form of international strings that can be in any script or language, so you must provide a name mapping resource to associate these three ISO string designations with user-readable names.

Listing 2-61 shows SamplePart's editor-to-string mapping.

Listing 2-61 Editor-to-string mapping

#define kPartClassName                 "som_SamplePart"
#define kSamplePartID                  "SampleCode::"kPartClassName
#define kSamplePartEditorUserString    "SamplePart 1.0"
#define kEditorUserStringMapId         kBaseResourceID+3

resource kODNameMappings (kEditorUserStringMapId) {
   kODEditorUserString,
   {  /* array Types: 1 elements */
      /* [1] */
      kSamplePartID,
      kODIsINTLText
      {
         smRoman,
         langEnglish,
         kSamplePartEditorUserString
      }
   }
};

Listing 2-62 shows SamplePart's kind-to-string mapping.

Listing 2-62 Kind-to-string mapping

#define kSamplePartKind                  kODISOPrefix "Apple:Kind:SamplePart"

#define kSamplePartKindUserString        "SamplePart"

#define kKindUserStringMapId             kBaseResourceID+4

resource kODNameMappings (kKindUserStringMapId) {
   kODKindUserString,
   {  /* array Types: 1 elements */
      /* [1] */
      kSamplePartKind,
      kODIsINTLText
      {
         smRoman,
         langEnglish,
         kSamplePartKindUserString
      }
   }
};

It is not necessary to provide user-readable names for OpenDoc's standard part categories because these names are already defined by OpenDoc. You should use these standard categories if at all possible. SamplePart is a bad example in this case--because SamplePart has no content, it cannot use any of the standard categories. OpenDoc's standard categories are listed in the OpenDoc Programmer's Guide for the Mac OS.

Listing 2-63 shows SamplePart's category-to-string mapping.

Listing 2-63 Category-to-string mapping

#define kSamplePartCategory                  kODISOPrefix "Apple:Category:Sample Code"
#define kSamplePartCategoryUserString        "Sample Code"
#define kCategoryUserStringMapId             kBaseResourceID+5

resource kODNameMappings (kCategoryUserStringMapId) {
   kODCategoryUserString,
   {  /* array KeyList: 1 elements */
      /* [1] */
      kSamplePartCategory,
      kODIsINTLText {
         smRoman,
         langEnglish,
         kSamplePartCategoryUserString
      }
   }
};

Mapping Kind to Mac OS Type

OpenDoc requires part editors to provide a one-to-one mapping of their part kinds to platform-specific file types. On the Mac OS, this table maps part kinds to old-style Mac OS four-letter file types. When OpenDoc creates documents from stationery or dragging content to the Finder, it uses this resource to figure out the OSType file type of the resulting file. The Finder uses this information to associate the proper icon with its kind.

Listing 2-64 shows SamplePart's kind-to-Mac-OS-type mapping.

Listing 2-64 Kind-to-Mac-OS-type mapping

#define kSamplePartKind                 kODISOPrefix "Apple:Kind:SamplePart"
#define kSamplePartDocumentOSType       'SPDC'
#define kOldMacOSTypeMapId              kBaseResourceID+6
resource kODNameMappings (kOldMacOSTypeMapId) {
   kODKindOldMacOSType,
   {  /* array KeyList: 1 elements */
      /* [1] */
      kSamplePartKind,
      kODIsMacOSType {
         kSamplePartDocumentOSType
      }
   }
};

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help